Release 10.1A: OpenEdge Reporting:
Query/Results Administration and Development

API basics

The Results API consists of a set of shared variables and a procedural interface. The following sections provide basic information about how to access the shared variables and procedures of the Results API in a feature or integration procedure.

Accessing shared variables

Results establishes and maintains a set of shared variables, called API shared variables, that you can access and set from a feature or integration procedure. API shared variables provide information about the current state of the Results application and the current query in Results. Table 3–4 provides summary information about the API shared variables available in Results.

Table 3–4: API shared variables

Shared variable name	Data type	Extent	Description
qbf–vers	CHARACTER	N/A	A version number for the current installation of Results.
qbf–module	CHARACTER	N/A	A character code representing the current Results view.
qbf–name	CHARACTER	N/A	The name of the current query in Results.
qbf–sortby	CHARACTER	N/A	A comma-separated list of field names to sort by. The fields are listed by precedence in the sort.
qbf–count	INTEGER	N/A	An integer representing the number of records returned by the current query.
qbf–governor	INTEGER	N/A	An integer representing the number of records to process in report, label, and export views. Zero (0) processes all records.
qbf–rc#	INTEGER	N/A	The number of fields (database, calculated, and arrays) in the current query.
qbf–rcn	CHARACTER	64	The name of each field in the current query and additional expression information.
qbf–rcc	CHARACTER	64	Information about each calculated field and stacked array in the current query.
qbf–rcg	CHARACTER	64	Information about aggregate fields in the query.
qbf–rcl	CHARACTER	64	Labels for each field in the current query.
qbf–rcf	CHARACTER	64	Formats for each field (database or calculated) in the current query.
qbf–rcp	CHARACTER	64	A comma-separated list of values for each field representing layout information for the field in a report, form, and label views.
qbf–rcw	INTEGER	64	The width in characters for each field in a report view of the current query.
qbf–rct	INTEGER	64	Data type identifiers for each field in the current query. The integer identifier corresponds to a list entry in the qbf–dtype shared variable.
qbf–dtype	CHARACTER	N/A	A comma-separated list of data types.

To access these API shared variables in a feature or integration procedure, you must define them in your procedure. Typically, you use the Defined Shared Variable statement to define a previously established shared variable for use in a procedure. However, Results provides the u-pvars.i include file to define the API shared variables for you.

Use the following syntax to reference the u-pvars.i include file in the feature or integration procedure:

Syntax

{aderes/u-pvars.i}

Once you reference this include file at the top of your procedure, you can access any of the API shared variables. For more information about referencing include files see the OpenEdge Development: Progress 4GL Reference . See the "Accessing and editing the current query" section for more information on how to use the API shared variables in a feature or integration procedure.

Using the procedural interface

Results provides an interface that allows you to manipulate Results queries and execute Results features from a feature or integration procedure. The procedure interface consists of six API procedures. All of the API procedures are located in the procedure library in the $DLC/gui directory. Table 3–5 provides summary information about the API procedures available for Results.

Table 3–5: API procedures

API procedure	Description
aderes/sffire.p	Executes a feature defined in Results from a feature or integration procedure.
aderes/vgrpti.p	Retrieves report information. This procedure returns information about the format of a report.
aderes/vgtbll.p	Retrieves the table list of the current query in Results.
aderes/vgtbli.p	Retrieves table information. This procedure accesses the join and selection criteria associated with a specified table in the current query in Results.
aderes/vstbll.p	Sets the table list for a new current query in Results.
aderes/vsrpti.p	Sets page size for the current query.
aderes/vstbli.p	Sets the table information associated with the current query.
aderes/vsexpi.p	Sets the export format for the current query.
aderes/vslbli.p	Sets the label format for the current query.

To use these API procedures in a feature procedure:

Use the RUN statement to call an API procedure from a feature procedure.
Define a local variable in the feature procedure for each input-output and output parameter specified in the API procedure call.

For more information, see the RUN statement and DEFINE VARIABLE statement in the OpenEdge Development: Progress 4GL Reference .The following sections of this chapter describe how to use the different API procedures in a feature procedure.

Executing a feature from a feature procedure

The API sffire.p procedure executes a feature from a feature procedure. With this capability, you can use features in Results as building blocks for other features. Use the following syntax to call the API sffire.p procedure from a feature procedure:

Syntax

RUN aderes/sffire.p ( INPUT featureId , INPUT args, OUTPUT result ) .

Parameters for the sffire.p procedure

The following list describes the parameters associated with the API sffire.p procedure:

INPUT featureId

A string value representing the name of a feature as defined in Results. For information about Results features, see Appendix A "Results Features."

INPUT args

A string value representing one or more arguments passed to the specified feature. Specify multiple arguments as a comma-separated list. If the feature specified does not take arguments, pass the unknown value (?) for this parameter. For information about arguments for Results features, see Appendix A "Results Features."

OUTPUT result

A logical value that indicates whether the API procedure executed successfully.

If you use the sffire.p API procedure in a feature procedure, you must define a variable for the result output parameter, as shown in Example 3–3.

Example 3–3: sffire.p

DEFINE VARIABLE result AS LOGICAL NO-UNDO.                     .                     .                     . RUN aderes/sffire.p (INPUT "FileOpen", INPUT ?, OUTPUT result).

In Example 3–3, FileOpen is a feature that does not take an argument list. If Results can execute the FileOpen feature, the OUTPUT parameter result returns a TRUE value.

Table 3–6 lists several Results features that you can use with the API sffire.p procedure. These features are important for developing other feature and integration procedures.

Table 3–6: Important Results features 

API feature	Argument	Description
AdminProgInitialize	None	Clears all information from the API shared variables.
AdminProgInstantiate	None	Initializes any unset API shared variables with valid default values.
AdminProgWrite4GL	proc-name,format	Generates 4GL code for the current query and view, placing the source in the file specified with the proc-name argument. The format argument must be the character g or r: Character g generates stand-alone code. Character r generates code dependent on the Results application.

For information about additional features in Results, see Appendix A "Results Features."

Testing the Results version number

The API shared variable qbf–vers contains a string value representing the Results product version number. The product version number consists of two digits separated by a decimal point, and followed by a letter (for example, 10.0A). Check the version number to verify that the environment you used to develop your feature and integration procedures matches the version of Results at the end-user site.

If the versions do not match, API changes between Results versions could cause erratic behavior. Feature and integration procedures that access API shared variables and procedures might yield error messages. Table 3–7 lists some of the error messages that can result from a change to the Results API between versions.

Table 3–7: The Results API and error messages 

Error message	Possible problem
** "aderes/proc-name" was not found. (293)	The API procedure referenced in a feature or integration procedure is no longer supported in the current version of Results.
** Unknown Field or Variable name - var-name. (201)	The API shared variable referenced in a feature or integration procedure is no longer supported in the current version of Results.
Mismatched parameter types passed to procedure proc-name. (3230)	The parameters required by an API procedure are different in the current version of Results.
Procedure proc-name sent sub-procedure proc-name mismatched parameters.	The parameters required by an API procedure are different in the current version of Results.

These errors can prevent the feature or integration procedure from executing. To avoid this problem, rebuild your application. See Chapter 2, "Administering Results," for more information about rebuilding an application.